package com.xisoft.common.imagert;

/**
 * JPEGImageEncoder Interface
 * 
 * JPEGImageEncoder compresses images into JPEG data streams and writes the JPEG stream to an OutputStream.
 * Image data that is to be encoded can be passed in as a Raster of image data or as a BufferedImage. Encoding
 * or the image data into the output JPEG stream is controlled by the parameters setting found in the
 * JPEGEncodeParam object.
 * <P>
 * 
 * ColorSpace comments: First off JPEG by specification is color blind! That said, this interface will perform
 * some color space conversion in the name of better compression ratios. There is no explicit mechanism in the
 * JPEGEncodeParam interface for controlling the Encoded ColorSpace of the data when it is written to the JPEG
 * data stream. If an approriate colorspace setting is not already defined it is recommended that colorspace
 * unknown is used. Some updates to the standard color space designations have been made to allow this decoder
 * to handle alpha channels. See the JPEGEncodeParam description for more details on additional color space
 * designations ( @see JPEGEncodeParam ).
 * <P>
 * 
 * This encoder will process interchange, and abbreviated JPEG streams.
 */

import java.awt.image.BufferedImage;
import java.awt.image.ColorModel;
import java.awt.image.Raster;
import java.io.IOException;
import java.io.OutputStream;

/**
 * JPEGImageEncoder encodes buffers of image data into JPEG data streams. Users of this interface are required
 * to provide image data in a Raster or a BufferedImage, set the necessary parameters in the JPEGEncodeParams
 * object and successfully open the <code>OutputStream</code> that is the destination of the encoded JPEG
 * stream.
 * 
 * The JPEGImageEncoder interface can encode image data into interchange, and abbreviated JPEG data streams
 * that are written to the OutputStream provided to the encoder.
 * <p>
 * Note that the classes in the com.sun.image.codec.jpeg package are not part of the core Java APIs. They are
 * a part of Sun's JDK and JRE distributions. Although other licensees may choose to distribute these classes,
 * developers cannot depend on their availability in non-Sun implementations. We expect that equivalent
 * functionality will eventually be available in a core API or standard extension.
 * <p>
 * 
 * @see JPEGCodec
 * @see JPEGEncodeParam
 * @see Raster
 * @see BufferedImage
 * @see OutputStream
 */
public interface JPEGImageEncoder
{
    /**
     * Return the stream the Encoder is currenlt associated with.
     */
    public OutputStream getOutputStream();
    
    /**
     * Set the JPEGEncodeParam object that is to be used for future encoding operations. 'jep' is copied so
     * changes will not be tracked, unless you call this method again.
     * @param jep The JPEGEncodeParam object to use for future encodings.
     * 
     */
    public void setJPEGEncodeParam(JPEGEncodeParam jep);
    
    /**
     * This returns a copy of the current JPEGEncodeParam object, if you want changes to affect the encoding
     * process you must 'set' it back into the encoder (either through setJPEGEncodeParam or by providing the
     * modified param object in the call to encode.
     * @return A copy of the current JPEGEncodeParam object
     */
    public JPEGEncodeParam getJPEGEncodeParam();
    
    /**
     * This is a factory method for creating JPEGEncodeParam objects. The returned object will do a credible
     * job of encoding the given BufferedImage.
     */
    public JPEGEncodeParam getDefaultJPEGEncodeParam(BufferedImage bi) throws ImageFormatException;
    
    /**
     * Encode a BufferedImage as a JPEG data stream. Note, some color conversions may takes place. The current
     * JPEGEncodeParam's encoded COLOR_ID should match the value returned by getDefaultColorID when given the
     * BufferedImage's ColorModel.
     * <P>
     * 
     * If no JPEGEncodeParam object has been provided yet a default one will be created by calling
     * getDefaultJPEGEncodeParam with bi.
     * 
     * @param bi The BufferedImage to encode.
     */
    public void encode(BufferedImage bi) throws IOException, ImageFormatException;
    
    /**
     * Encode a BufferedImage as a JPEG data stream. Note, some color conversions may takes place. The jep's
     * encoded COLOR_ID should match the value returned by getDefaultColorID when given the BufferedImage's
     * ColorModel.
     * <P>
     * 
     * This call also sets the current JPEGEncodeParam object. The given JPEGEncodeParam object will be used
     * for this and future encodings. If jep is null then a new JPEGEncodeParam object will be created by
     * calling getDefaultJPEGEncodeParam with bi.
     * 
     * @param bi The BufferedImage to encode.
     * @param jep The JPEGEncodeParam object used to control the encoding.
     */
    public void encode(BufferedImage bi, JPEGEncodeParam jep) throws IOException, ImageFormatException;
    
    /**
     * Returns the 'default' encoded COLOR_ID for a given ColorModel. This method is not needed in the simple
     * case of encoding Buffered Images (the library will figure things out for you). It can be useful for
     * encoding Rasters. To determine what needs to be done to the image prior to encoding.
     * 
     * @param cm The ColorModel to map to an jpeg encoded COLOR_ID.
     * @return The default mapping of cm to a jpeg Color_ID note that in a few cases color conversion is
     *         required.
     */
    public int getDefaultColorId(ColorModel cm);
    
    /**
     * This is a factory method for creating JPEGEncodeParam objects. It is the users responsiblity to match
     * the colorID with the data contained in the Raster. Failure to do so may lead to either poor compression
     * or poor image quality. If you don't understand much about JPEG it is strongly reccomended that you
     * stick to the BufferedImage interfaces.
     */
    public JPEGEncodeParam getDefaultJPEGEncodeParam(Raster ras, int colorID) throws ImageFormatException;
    
    /**
     * This is a factory method for creating JPEGEncodeParam objects. It is the users responsiblity to match
     * the colorID with the given number of bands, which should match the data being encoded. Failure to do so
     * may lead to poor compression and/or poor image quality. If you don't understand much about JPEG it is
     * strongly recommended that you stick to the BufferedImage interface.
     * 
     * @param numBands the number of bands that will be encoded (max of four).
     * @param colorID the COLOR_ID for the encoded data. This is used to set reasonable defaults in the
     *            parameter object. This must match the number of bands given.
     */
    public JPEGEncodeParam getDefaultJPEGEncodeParam(int numBands, int colorID) throws ImageFormatException;
    
    /**
     * This is a factory method for creating a JPEGEncodeParam from a JPEGDecodeParam. This will return a new
     * JPEGEncodeParam object that is initialized from the JPEGDecodeParam object. All major pieces of
     * information will be initialized from the DecodeParam (Markers, Tables, mappings).
     * @param jdp The JPEGDecodeParam object to copy.
     */
    public JPEGEncodeParam getDefaultJPEGEncodeParam(JPEGDecodeParam jdp) throws ImageFormatException;
    
    /**
     * Encode a Raster as a JPEG data stream. Note that no color conversion takes place. It is required that
     * you match the Raster to the encoded COLOR_ID contained in the current JPEGEncodeParam object.
     * <P>
     * 
     * If no JPEGEncodeParam object has been provided yet a new JPEGEncodeParam object will be created by
     * calling getDefaultJPEGEncodeParam with ras and COLOR_ID_UNKNOWN.
     * 
     * @param ras The Raster to encode.
     */
    public void encode(Raster ras) throws IOException, ImageFormatException;
    
    /**
     * Encode a Raster as a JPEG data stream. Note that no color conversion takes place. It is required that
     * you match the Raster to the encoded COLOR_ID contained in the JPEGEncodeParam object.
     * 
     * If jep is null a new JPEGEncodeParam object will be created by calling getDefaultJPEGEncodeParam with
     * ras and COLOR_ID_UNKNOWN.
     * 
     * @param ras The Raster to encode.
     * @param jep The JPEGEncodeParam object used to control the encoding.
     */
    public void encode(Raster ras, JPEGEncodeParam jep) throws IOException, ImageFormatException;
}
